Migrate doc generation to docbook/fop (postgresql approach) #63
Conversation
vitcpp
force-pushed
the
doc-improve-1
branch
2 times, most recently
from
48a30ee to
0ea8381
Compare
There was a problem hiding this comment.
Thanks for tackling this infrastructure task!
I'm not familiar enough with postgres doc practices to have an informed opinion about every line in the change, but I've built the PDFs and the multipage HTML, which both looks good.
I also don't know what to write instead of the tbw-s. Perhaps we should create an issue for them?
Finally, I'm not sure if we want to smuggle such a change in here, but since I ran into it during review: sect. 2.2 says "You will need PostgreSQL 9.1 or above." almost certainly is wrong these days. Perhaps we can say "The minimal postgres version for any given pgsphere version can be found at xy" (where I'm not sure what "xy" would be at this point)? Or just drop the sentence entirely on grounds that it will probably always under-updated and no information is better than wrong information?
|
This might be beyond the scope of this PR, but I think it would be a good to have a GitHub Action that generates the HTML documentation whenever there's a change merged/pushed to the master branch and then publishes the generated HTML to GitHub Pages. Something like this: https://gist.github.com/MichaelCurrin/a698731096f78240f653faf9a9127cba |
|
@msdemlei This change is the first step to improve the document generation infrastructure. I propose to cleanup the content after this change because it is a long time work with a lot of PRs, I guess. Thank you for the report. Now I'm concerned - can we synchronize our repos after this change? Is this change suitable for you? If you have some problems with this change, then we have to reconsider the solution. In this PR I removed the chapters with TBW. I think, it is not a good thing to have empty chapters. We can add such chapters later with some content. I agree, we may create another Issues for that. |
@esabol I agree, it is a very good idea! Thank you! I will investigate how to implement it. |
|
Two (different) instances of the minimum supported PostgreSQL version in the documentation: Line 39 in fb93eb4 Line 22 in fb93eb4 These both need to be updated to reflect the current minimum (10.0?). Do you want to do that here in this PR or in a separate PR? I suppose you could define a variable for this in |
The document generation was redesigned to use the same approach as postgresql does. It uses fop for printable doc generation and xsltproc for html generation. Postgresql stylesheets are used (with some minor changes). Fixed version propagation when generating the doc. Now, the version is placed in Makefile.common.mk file that is used in doc generation process. The following make rules were implemented: - make pdf (generates printable doc in A4 and US Letter format) - make pg_sphere-<VERSION>-A4.pdf (generate the printable doc in A4) - make pg_sphere-<VERSION>-US.pdf (generate the printable doc in USLetter) - make html (generates single-page and multi-page html) - make html-singlepage (generate single-page html only) - make html-multipage (generate multi-page html only)
Remove inclusion of 'pg_config --pgxs' makefile because it is not required to create the documentation. This makefile was designed to be included in top-level extension makefile. Inclusion in the doc/Makefile results into some unexpected behaviour when using 'install' or 'all' rules. Remove gmake -C doc install in .travis.yml because this target didn't do anything. I guess that the installation of the manual should be implemented in the top-level extension Makefile file, not in the doc/Makefile.
vitcpp
force-pushed
the
doc-improve-1
branch
from
b06058f to
48c3d5e
Compare
|
Rebased to the latest master. |
Dear All,
Please, consider this PR that implements doc generation as postgresql does.
The document generation was redesigned to use the same approach as postgresql does. It uses fop for printable doc generation and xsltproc for html generation. Postgresql stylesheets are used (with some minor changes).
Fixed version propagation when generating the doc. Now, the version is placed in Makefile.common.mk file that is used in doc generation process.
The following make rules were implemented: